Model Search API

Search and discover AI models available in the Runware platform. Filter and find the right model for your generation tasks.

Introduction

The Model Search API enables discovery of available models on the Runware platform, providing search and filtering capabilities across public models from the community and private models within your organization.

Models discovered through this API can be used immediately in generation tasks by referencing their AIR identifiers. This enables dynamic model selection in applications and helps discover new models for specific use cases.

The search works across model names, versions, tags, and other metadata. Multiple filters can be combined to narrow results by category, type, architecture, and visibility. Results are returned in a paginated format with a default of 20 models per page, controlled by the limit and offset parameters.

Request

The Runware API always accepts an array of objects as input, where each object represents a specific task to be performed. The structure of the object varies depending on the type of the task. For this section, we will focus on the parameters related to the model search task.

The following JSON snippet shows the basic structure of a request object.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const result = await client.modelSearch({
  search: 'realistic',
  tags: 'photorealistic',
  category: 'checkpoint',
  type: 'base',
  architecture: 'sdxl',
  visibility: 'all',
  offset: 0,
  limit: 20
})

import asyncio
import os

from runware import Runware


async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        result = await client.model_search({
            "search": "realistic",
            "tags": "photorealistic",
            "category": "checkpoint",
            "type": "base",
            "architecture": "sdxl",
            "visibility": "all",
            "offset": 0,
            "limit": 20
        })


asyncio.run(main())

curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "modelSearch",
      "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
      "search": "realistic",
      "tags": "photorealistic",
      "category": "checkpoint",
      "type": "base",
      "architecture": "sdxl",
      "visibility": "all",
      "offset": 0,
      "limit": 20
    }
  ]'

runware model search \
  -q realistic \
  --tags photorealistic \
  --category checkpoint \
  --type base \
  --architecture sdxl \
  --visibility all \
  --offset 0 \
  --limit 20

{
  "taskType": "modelSearch",
  "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
  "search": "realistic",
  "tags": "photorealistic",
  "category": "checkpoint",
  "type": "base",
  "architecture": "sdxl",
  "visibility": "all",
  "offset": 0,
  "limit": 20
}

taskType stringrequiredvalue: modelSearch: Identifier for the type of task being performed

taskUUID stringUUID v4: UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.

search stringrequired: Search query to find models by name, description or AIR ID.

tags array of strings: Filter models by specific tags.

category string: Filter models by category.
Allowed values5 values

type string: Filter checkpoint models by type. Only applicable when category is checkpoint.
Allowed values3 values

architecture string: Filter by model architecture.

conditioning string: Filter ControlNet models by their conditioning type.
Allowed values21 values

visibility stringdefault: all: Filter by visibility status (e.g., public, private, all).
Allowed values3 values

limit integermin: 1max: 100default: 20: Maximum number of results to return.

offset integermin: 0default: 0: Number of results to skip for pagination.

Response

Results will be delivered in the format below.

{
  "data": [
    {
      "results": [
        {
          "name": "Promissing_Realistic_XL",
          "air": "civitai:305149@392545",
          "tags": [
            "photorealistic",
            "base model",
            "sci-fi",
            "photo",
            "woman",
            "fantasy",
            "photorealism",
            "rpg",
            "general use",
            "close up",
            "close up shot",
            "promissing_realistic_xl"
          ],
          "heroImage": "https://mim.runware.ai/r/66a70a0bb7c38-450x450.jpg",
          "category": "checkpoint",
          "private": false,
          "comment": "",
          "version": "v22",
          "architecture": "sdxl",
          "type": "base",
          "defaultWidth": 1024,
          "defaultHeight": 1024,
          "defaultSteps": 20,
          "defaultScheduler": "Default",
          "defaultCFG": 7.5
        }
      ],
      "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
      "taskType": "modelSearch",
      "totalResults": 2
    }
  ]
}

taskType stringrequiredvalue: modelSearch: Identifier for the type of task this response belongs to.

taskUUID stringrequiredUUID v4: UUID v4 identifier echoed from the original request, used to match async responses to their tasks.

totalResults integerrequiredmin: 0: Total number of models matching the search criteria.

results array of objectsrequired

List of models found.

Properties11 properties

results » air air stringrequired: Artificial Intelligence Resource identifier.

results » name name stringrequired: Name of the model.

results » version version stringrequired: Version of the model.

results » category category stringrequired: Category of the model (e.g., checkpoint, lora).

results » architecture architecture string: Model architecture (e.g., sdxl, flux).

results » imageURL imageURL stringrequiredURI: URL of the model's representative image.

results » thumbnailURL thumbnailURL stringrequiredURI: URL of the model's thumbnail image.

results » tags tags array of strings: List of tags associated with the model.

results » private private boolean: Whether the model is private.

results » primary primary boolean: Whether this is the primary version of the model.

results » baseModel baseModel string: The base model this model is derived from.